home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BBS Toolkit
/
BBS Toolkit.iso
/
doors_1
/
jpdoor32.zip
/
JPDOOR.DOC
< prev
next >
Wrap
Text File
|
1992-02-26
|
37KB
|
915 lines
┌──────────────────────────────────────────────┐
│ MOTOR CITY SOFTWARE │
│ ┌──────────────────────────────────────┐ │
│ │ JPDoor - Version 3.1 SE │ │
│ │ ┌──────────┐ │ │
│ │ │\ │ │ │
│ │ │ \ │ │ │
│ │ │ \ P │ │ │
│ │ │ \ A │ │ │
│ │ │ │ S │ │ │
│ │ │ │ C │ │ │
│ │ 5.5 │ │ A │ 6.0 │ │
│ │ │ o│ L │ │ │
│ │ │ │ │ │ │
│ │ \ │──────┘ │ │
│ │ \ │ │ │
│ └──────────────\ │─────────────────────┘ │
│ The Ultimate \│ Door Writing Unit. │
└────────────────────┴─────────────────────────┘
JPDoor - Version 3.1 SE
Copyright 1990,1991,1992 by Motor City Software.
All Rights Reserved
J P D O O R D O C U M E N T A T I O N
╒════════════════════════════════════════════════════════════════════════════╕
│░░░░░ TABLE OF CONTENTS ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘════════════════════════════════════════════════════════════════════════════╛
Motor City Software ............................. 3
Licensing Information .......................... 4
Support Systems ................................. 4
Acknowledgements ............................... 5
Getting Started With JPDoor
The Uses Statement ........................ 6
Trapping Halt Codes ....................... 6
Trapping Extended Keys .................... 9
Getting the User Information .............. 12
Initializing the Fossil Driver ............ 13
Initializing ANSI Color Sequences ......... 14
The Status Bar ............................ 14
Fossil Output Buffering ................... 15
JPDoor Reference Section .................. See File JPDOOR.REF
[2] JPDoor 3.1.Doc
╒═════════════════════════════════════════════════════════════════════════════╕
│░░░░░░ MOTOR CITY SOFTWARE ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘═════════════════════════════════════════════════════════════════════════════╛
Motor City Software is a Shareware Programming Partnership composed
of four different Programmers, which each bring their own special talents
to this unique partnership:
Rod Hancock John Parlin Jeff Wilson Peter Kling
Oshawa Ontario Hopkins MN Bowmanville Ont Albany NY
CANADA USA CANADA USA
[3] JPDoor 3.1.Doc
╒═════════════════════════════════════════════════════════════════════════════╕
│░░░░░░ LICENSING INFORMATION ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘═════════════════════════════════════════════════════════════════════════════╛
This program is not Freeware. This is SHAREWARE which means it is user-
supported software. If you use this program for more than 30 days, you are
required to register or remove it from your system. The registration fee is
a mere $30.00 and is not a lot to ask considering the time and effort required
for a toolkit of this nature.
JPDOOR is Copyright 1990,1991,1992 by Motor City Software and all rights
are reserved. You may copy this program and documentation for backup purposes.
You also may copy and share UNMODIFIED copies of the program package, pro-
viding that the copyright notice is reproduced and included on all copies.
You may not sell the product for a fee and/or distribute the product
along with other products without expressed written permission from Motor
City Software, nor may you modify or remove the Copyright Notice from the
program or the documentation.
You may not distribute programs which you have created using JPDoor
without first registering JPDoor with the author. You may not accept com-
pensation for programs created using JPDoor without registering JPDoor with
the authors.
This unit was written to aid programmers in writing RemoteAccess 0.01
thru 1.11 and QuickBBS 2.62 thru 2.75 compatible door programs using Turbo
Pascal* 5.5 and Turbo Pascal* 6.0.
Use of this product constitutes acceptance of these terms.
╒═════════════════════════════════════════════════════════════════════════════╕
│░░░░░░ SUPPORT SYSTEMS ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘═════════════════════════════════════════════════════════════════════════════╛
If you have any comments, suggestions or bug reports please address them to
Rod Hancock at FidoNet 1:229/418. For additional support or the latest files
a list of the Motor City Software Support Systems is included in this archive
as SUPPORT.LST
[4] JPDoor 3.1.Doc
╒═════════════════════════════════════════════════════════════════════════════╕
│░░░░░░ ACKNOWLEDGEMENTS ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘═════════════════════════════════════════════════════════════════════════════╛
The release of JPDoor has been a cooperative effort. Our sincere
gratitude goes out to those who helped with the development of one of the
most popular Door Writing Toolkits available.
The contributors towards past versions were:
- Cary Howell, QuickAccess BBS (1:379/207), The Manhatten Project
Cary really added a lot to the code providing us with the status bar,
text file control codes, screen handling, and other enhancements to
existing blocks of code.
- Scott Davis, Phoenix Starfighter BBS (1:3616/20)
Scott provided his assistance whenever I asked for it and volunteered
even more. Thanks to Scott, we now have the ability to trap extended
keys from the local console or the remote. Scott contributed in many
areas and has helped to keep JPDoor compatible with QuickBBS 2.64
systems. Scott also enhanced the unit by combining ShowAnsiFile and
ShowTextFile to make one procedure called ShowFile.
- Mark Cook, Wizardry BBS (1:104/630)
Mark provided us with the initial idea of far calls in JPDoor so that
we could trap unexpected exits. Some of Mark's TRAPEXIT.PAS code is
still included in this release.
- Robert Van Hoeven and Tom Ordelman of European Cybernetics
Robert optimized the code and cleaned up some of my not-so-pretty
stuff for release 2.4c. Tom coordinated the effort. Thanks to these
two, we can read the code again!
- Peter Kling of The Computer Group Ltd (1:267/169.0).
Peter provided some enhancements to make the error handling
procedures more readable for the user and the sysop. The
error handling code had been imported directly from Packer.
- Andrew Milner & Continental Software for unlimited support
and a great BBS package without which some of the new features
of JPDoor would not be possible.
- A special thanks to all the beta testers for all the suggestions
and help in ironing out the bugs.
And a big thanks to all the users out there who have shown an interest
in this product. Your support is what generates new releases. Program
updates will continue to be made as long as there is user support in the
form of product registrations.
(* Turbo Pascal is trademarked by Borland International, Inc.)
[5] JPDoor 3.1.Doc
╒═════════════════════════════════════════════════════════════════════════════╕
│░░░░░░ GETTING STARTED WITH JPDOOR ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
╘═════════════════════════════════════════════════════════════════════════════╛
The USES statement:
-------------------
To use JPDoor with your door program, you'll need to put it into your
USES statement:
USES DOS, CRT, JPDoor31 ;
code segment:
--------------------------------------------------------------------------
| PROGRAM MyDoorProgram ; |
| USES DOS, CRT, JPDoor31 ; |
| ..... |
| ... |
| {your program continues} |
--------------------------------------------------------------------------
JPDoor needs to find MAPPED.TPU to perform some of its functions.
MAPPED.TPU is included in the JPDoor 3.1 distribution archive. You
are not required to include it in your USES statement, however, it
must reside in your Turbo Pascal UNIT directory.
Trapping HALT codes (exits):
----------------------------
The include file TRAPEXIT.PAS contains a far call procedure called
TRAPEXIT. The TRAPEXIT procedure, in turn, calls a TERMINATE procedure
and passes the halt code to it. You could conceivably do all your
clean-up, etc. right inside of the TRAPEXIT procedure and not call
another procedure such as TERMINATE but for the sake of demonstration,
let us say that the far call procedure TRAPEXIT does call the procedure
TERMINATE.
First of all, let's get setup to trap HALT codes. Here's what you'll
need to do:
1) Incorporate the following TERMINATE procedure. The TRAPEXIT
procedure will call this procedure, passing the HALT code to
it. If the HALT is a runtime error, TRAPEXIT will report that
instead of calling TERMINATE.
[6] JPDoor 3.1.Doc
Trapping HALT codes (continued):
--------------------------------
-----------------------------------------------------------------------------
| PROCEDURE Terminate(HaltCode : BYTE) ; |
| BEGIN |
| CASE HaltCode OF |
| 0 : WRITELN('Normal termination') ; {normal terminate - no action} |
| 1 : BEGIN |
| WRITELN('Carrier lost') ; |
| EndGame ; {call EndGame proc. and write user info} |
| END ; |
| 2 : BEGIN |
| WRITELN('Time limit exceeded') ; |
| { do what you would want done if the caller's time |
| limit was exceeded } |
| END ; |
| 3 : BEGIN |
| WRITELN('User inactivity timeout') ; |
| { do what you would want done if user was inactive } |
| END ; |
| 4 : BEGIN |
| WRITELN('Dorinfo1.Def file not found') ; |
| { not good - do what you would want done in this situation} |
| END ; |
| 5 : BEGIN |
| WRITELN('Exitinfo.Bbs file not found') ; |
| { not good - do what you would want done in this situation} |
| END ; |
| 6 : BEGIN |
| WRITELN('Directory read/change error') ; |
| { this is a nasty. You should close files and HALT(0) } |
| END ; |
| 7 : BEGIN |
| WRITELN('CTS - Clear To Send Error/Time Out'); |
| { most likely carrier has been dropped, close files } |
| { and then Halt(0) } |
| END |
| 8 : WRITELN('RAXIT Semaphore forced Exit'); |
| 9 : Writeln('Door.Sys file not found');
| END ; |
| END ; |
---------------------------------------------------------------------------
[7] JPDoor 3.1.Doc
Trapping Halt Codes (continued):
--------------------------------
Place your TERMINATE procedure anywhere within your program. The
only stipulation is that you must place it BEFORE the line that
includes the file TRAPEXIT.PAS.
2) Next, be sure to include the TrapExit.Pas file:
---------------------------------------------------------------------------
| {$I TRAPEXIT} |
---------------------------------------------------------------------------
3) Now, in the Main Body of your program code, you will need to add
the following line:
---------------------------------------------------------------------------
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| ...... |
| ... |
| your program continues |
---------------------------------------------------------------------------
The statements ASSIGN(OutPut,'') and REWRITE(OutPut) will allow
ANSI escape codes to be properly displayed on the local console.
The statement DoorExit := TrapExit will setup halt code trapping.
Now HALT code trapping is in effect. When a HALT code is encountered,
the TRAPEXIT procedure will be called. TRAPEXIT will determine if a
Runtime Error has occurred or if a HALT code was used. If a HALT code
was used, TRAPEXIT will call your program's TERMINATE procedure, passing
the HALT code to it.
If you do not assign a procedure to DoorExit as shown, HALT codes will
not be trapped.
[8] JPDoor 3.1.Doc
Trapping Extended Keys:
-----------------------
JPDoor allows you to define up to 20 extended keys for Sysop/Local use
as well as 20 keys for End-User/Remote use. This would allow the Sysop
to setup procedures that can be called at the press of an ALT key or
Function key. This would also be good for a door program that required
the end-user to press, for example, an up or down arrow key.
Extended codes are codes that return a null (character #0) first, and
then a second, extended code second. For example, ALT-C is a two-code key.
It's a null (ASCII #0) code followed by an ASCII #46.
Other codes are, for example, control codes such as CONTROL-R which
is an ASCII #18. This type of control code is not an extended code yet
you might want to trap for it and have a procedure called.
So how do we setup to trap these keys? For the sake of this example,
let's say that our goal is to trap for an ALT-C. Let's say that we want
to call an online chat procedure called CHAT when ALT-C is pressed.
The first thing we need to do is to tell JPDoor the key codes we want
to trap and the procedure name to call. Since this is a Sysop/Local
key/function we'll use SysopKey and SysopProc. Let's define it as follows:
---------------------------------------------------------------------------
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
---------------------------------------------------------------------------
We can define up to 20 keys and procedures here but we'll just work with
this one. Next, we'll need to set the unit variable 'SysopKeysOn' to TRUE:
---------------------------------------------------------------------------
| SysopKeysOn := TRUE ; |
---------------------------------------------------------------------------
[9] JPDoor 3.1.Doc
Trapping Extended Keys (continued):
-----------------------------------
Next, we need to take a look at our SYSOPKEY.PAS far call include file.
Here's what it might look like:
--------------------------------------------------------------------------
| {$F+} |
| PROCEDURE ALT_C ; |
| BEGIN |
| SysopKeysOn := FALSE ; {turn off key trapping for the duration } |
| CHAT ; {call your CHAT procedure in your code } |
| SysopKeysOn := TRUE ; {turn key trapping back on } |
| END ; |
| {$F-} |
--------------------------------------------------------------------------
Pretty straight forward, isn't it? The far call procedure ALT_C turns
off key trapping (you don't want to be able to chat within CHAT do you?).
It then calls your procedure called CHAT. Lastly, it turns key trapping
back on again. Your program will then continue where it was before ALT-C
was pressed.
So how's our main program code segment looking so far? Let's take a look:
--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| ...... |
| ... |
| your program continues |
| |
--------------------------------------------------------------------------
[10] JPDoor 3.1.Doc
Trapping Extended Keys(continued):
----------------------------------
Now if you wanted to enable a user to enter extended codes or control
codes, you use the same theory as with Sysop/Local keys only we work with
the variables UserKey[1..20], UserProc[1..20], and UserKeysOn (BOOLEAN).
For example, let's say that we want our door program to allow the user
to press CONTROL-R to redraw the screen. Let's say that you already have
a procedure called REDRAW in your program. Let's create a file called
USERKEY.PAS. Here's what it might look like:
--------------------------------------------------------------------------
| {$F+} |
| PROCEDURE CONTROL_R ; |
| BEGIN |
| UserKeysOn := FALSE ; |
| REDRAW ; |
| UserKeysOn := TRUE ; |
| END ; |
| {$F-} |
--------------------------------------------------------------------------
Now here's how your main program code might look:
--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| ..... |
| ... |
| your program continues |
--------------------------------------------------------------------------
It works the way the SysopKey/SysopProc does. You can define up to 20
SysopKey, UserKey, SysopProc, and UserProc's. There's no need to initialize
them. Toggling SysopKeysOn and UserKeysOn TRUE/FALSE is all you need to
turn them on or off.
[11] JPDoor 3.1.Doc
Getting the User Information:
-----------------------------
Now we're at a point where we can get the online user's information.
Previous versions of JPDoor required the presence of both a DORINFOx.DEF
and an EXITINFO.BBS file created which are created by RemoteAccess and
QuickBBS. Because many doors are used on a wide variety of BBS types,
and many of them are not capable of producing an Exitinfo.bbs, this is
now optional. If your door does not need to update any user information,
simply include the following in your program BEFORE calling GetDorinfo.
CkExitInfo := False;
Finally, JPDoor will now read a GAP style DOOR.SYS file as well as the
DOOR.SYS created by RemoteAccess. If you wish to use this file, rather
than DORINFOx.DEF then include the following BEFORE calling GetDorinfo.
DoorSys := True;
The GetDorinfo routine will automatically detect the correct structures
for any of these drop files:
QBBS 2.64 - 2.75 EXITINFO.BBS
RemoteAccess V0.03 - 1.11 EXITINFO.BBS
RemoteAccess V1.xx DOOR.SYS (DoorWay Style)
GAP DOOR.SYS (Also created with PCBoard)
To get information about the user currently online, we must pass two
parameters to GetDorInfo.
They are:
1: the current node
2: the path to DORINFOx.DEF and EXITINFO.BBS or DOOR.SYS
JPDoor is designed to support RemoteAccess 1.11 data structures.
However, if the program you create is run on a QuickBBS system,
or earlier releases of RemoteAccess, the EXITINFO.BBS file will be
converted automatically to RemoteAccess 1.11 format upon program startup.
It will also be automatically converted back to its original format when
your program ends. No intervention or conversion is required by your
program!
So now let's add the GetDorInfo procedure to your program code:
--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| ...... |
| .... |
| your program continues |
--------------------------------------------------------------------------
[12] JPDoor 3.1.Doc
Getting the User Information: (Continued)
-----------------------------------------
This example uses the current directory as the directory to read
DORINFOx.DEF and EXITINFO.BBS from. Once done, we have all the user
and FOSSIL port information needed by JPDoor.
Initializing the FOSSIL Driver:
-------------------------------
This is really straight forward. You should always use a FOSSIL driver
when executing a door program. Whether or not you're local, you still
need one installed for proper I/O. We're at a good spot in your main
program segment to check/initialize the FOSSIL driver. Let's add the
following lines of code:
--------------------------------------------------------------------------
| |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
--------------------------------------------------------------------------
Of course you can use any halt code greater than ten instead of zero.
What this block of code does is checks the value of the BOOLEAN function
'SetFossil'. When referrenced, SetFossil calls an internal procedure
which initializes the FOSSIL driver and returns a TRUE or FALSE depending
on its success.
Let's add this to your program code:
--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
| ...... |
| ... |
| your program continues |
--------------------------------------------------------------------------
[13] JPDoor 3.1.Doc
Initializing ANSI Color Sequences:
----------------------------------
Next we need to initialize ANSI colors. Whether or not a user of your
program has ANSI turned on, you should still include this segment in your
program code. If the user does not have ANSI turned on, the procedure
'SetColor' will exit without performing any tasks.
--------------------------------------------------------------------------
| {$I TRAPEXIT} |
| {$I SYSOPKEY} |
| {$I USERKEY} |
| BEGIN { Main - Example } |
| ASSIGN(OutPut,'') ; |
| REWRITE(OutPut) ; |
| DoorExit := TrapExit ; |
| SysopKey[1] := #0 + #46 ; |
| SysopProc[1] := ALT_C ; |
| SysopKeysOn := TRUE ; |
| UserKey[1] := #18 ; |
| UserProc[1] := CONTROL_R ; |
| UserKeysOn := TRUE ; |
| GetDorInfo(Node,'') ; |
| IF NOT SetFossil THEN BEGIN |
| WRITELN(#7,'WARNING! Fossil not detected!') ; |
| HALT(0) ; |
| END ELSE WRITELN('Fossil detected') ; |
| SetColor(0,7,0) ; |
| ...... |
| ... |
| your program continues |
--------------------------------------------------------------------------
The Status Bar
--------------
JPDoor also provides a 2 line Status Bar at the bottom of the screen.
This is optional and may be turned on and off by you with the StatusLineOn
Boolean variable.
You may also change the default display of the status bars simply by
putting your own info into the variables StatLineA[X] and StatLineB[X]
where X is a number from 1 to 9. These coincide with funtion keys 1 - 9
and F-10 will turn OFF the status Bar. These variables are of type
String[79];
The following codes are supported in the statusline string:
~C Current Time
~R Time Remaining
~S Security Level
~A [ANSI] or [MONO]
~B Baud Rate
We have now included all the initialization functions that are required
by JPDoor. Your program code can continue at this point!
[14] JPDoor 3.1.Doc
FOSSIL Output Buffering:
------------------------
JPDoor supports hotkeys. In order for JPDoor to act quickly when a
hot-key is pressed, output buffering does not normally take place. In
other words, JPDoor will send out one character at a time to the FOSSIL
output buffer and wait until that character has been sent from the buffer
before sending another one.
With programs written using JPDoor that do not utilize hot-keys, output
may be buffered which may increase the program's speed on the host computer.
If output buffering is used during a program which utilizes hot-keys,
hot-keys will still function but there may be a delay before display is
interrupted after a valid hot-key is pressed.
To turn on JPDoor's use of output buffering, you must set the DOS
environment variable OUTBUFF to ON. You can do this in a batch file
which calls the door program for which you want output buffering.
Let's say we want to execute a door program that was compiled using
JPDoor. In this example, the program is called DOORPROG.EXE. Here's a
little batch file segment that calls DOORPROG.EXE:
Menu Type 7 Optional Data Field Contents:
\COMMAND.COM /C \RA\MYDOOR.BAT
MYDOOR.BAT:
SET OUTBUFF=ON
DOORPROG.EXE
SET OUTBUFF=OFF
This batch file segment turns on JPDoor's output buffering, calls
the door program DOORPROG.EXE, and then turns JPDoor's output buffering
off again before returning operation to the BBS.
[15] JPDoor 3.1.Doc
